build(docs): Update api-markdown-documenter and utilize new hierarchy options #23504
Conversation
github-actions
bot
added
area: website
public api change
| docs/api | ||
| !docs/api/index.mdx | ||
| versioned_docs/*/api | ||
| !versioned_docs/*/api/index.mdx |
There was a problem hiding this comment.
Opted to exclude specific files, rather than blanket-excluding mdx files. This will let us (theoretically) move our API docs to mdx in the future.
| @@ -6,13 +6,13 @@ sidebar_position: 10 | |||
|
|
|||
| {/* Note: these contents are new and should be reviewed. The current website's API docs landing page has no description about what the packages do / when to use them. It's not very useful. */} | |||
|
|
|||
| To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework.md). | |||
| To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework/index.md). | |||
There was a problem hiding this comment.
We have to specify index here because we are expressing these links via file paths rather than routes. This is the recommended pattern.
| @@ -5,7 +5,7 @@ sidebar_label: fluid-framework | |||
|
|
|||
| # fluid-framework Package | |||
|
|
|||
| The fluid-framework package bundles a collection of Fluid Framework client libraries for easy use when paired with a corresponding service client package (for example, [@fluidframework/azure-client](/docs/deployment/azure-fluid-relay) or [@fluidframework/tinylicious-client](/docs/testing/tinylicious)). | |||
| The fluid-framework package bundles a collection of Fluid Framework client libraries for easy use when paired with a corresponding service client package (for example, [@fluidframework/azure-client](../deployment/azure-fluid-relay) or [@fluidframework/tinylicious-client](../testing/tinylicious)). | |||
There was a problem hiding this comment.
Relative paths are preferred
| [ApiItemKind.Model]: HierarchyKind.Document, | ||
| [ApiItemKind.Namespace]: HierarchyKind.Folder, | ||
| [ApiItemKind.Package]: HierarchyKind.Folder, |
There was a problem hiding this comment.
These values are the defaults for their respective types, but since we override document naming policy for them, seems reasonable to add them here explicitly to make the relationship clear.
@alexvy86 I hadn't even noticed the churn there. I need to do a better job of remembering to check the lockfile changes in my own PRs... Did we recently update our lockfile versions elsewhere in the repo? These changes bumped the version from 6 to 9. I notice that the root lockfile is already on 9. Did we forget to update docs in some previous upgrade pass? |
|
🔗 No broken links found! ✅ Your attention to detail is admirable. linkcheck output |
Yeah, since #23318 the whole repo is on pnpm 9 now which comes with the lockfile update. Seems like we missed updating the lockfile for docs in that PR though. |
Josmithr
deleted the
docs/update-api-markdown-documenter-for-hierarchy-fixes
branch
Update dev dependency on
@fluid-tools/api-markdown-documenterand leverage new "hierarchy" capabilities to move "folder" item documents (packages and namespaces) into their folders, renamed toindex.E.g.,
File structure before:
After:
This makes the breadcrumbs and navigation drop-downs generated by docusaurus better match the intended hierarchy.
E.g.,
Namespace appearance in the nav before:
Namespace appearance after:
Breadcrumb before:
Breadcrumb after:
AB#24263